home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / Extras / NewIconsV4 / Developers / Autodocs / newicon.doc
Text File  |  1997-09-24  |  9KB  |  265 lines
  1. TABLE OF CONTENTS
  2.  
  3. newicon.library/--Introduction--
  4. newicon.library/FreeNewDiskObject
  5. newicon.library/FreeRemappedImage
  6. newicon.library/GetDefNewDiskObject
  7. newicon.library/GetNewDiskObject
  8. newicon.library/PutNewDiskObject
  9. newicon.library/RemapChunkyImage
  10.  
  11. newicon.library/--Introduction--             newicon.library/--Introduction--
  12.  
  13. The goal behind newicon.library is to offer an interface for the 
  14. application programmer wishing to directly support NewIcons, be it icon 
  15. editors to Workbench replacements.  This ensures that your product will 
  16. be able to support NewIcons even if the Newicons executable isn't running.
  17.  
  18. The standard procedure is to call GetNewDiskObject(), and check if any 
  19. of the ndo_NormalImage or ndo_SelectedImage fields are NULL.  If they are, 
  20. then this icon has no newicon data, so you can use the ndo_StdObject 
  21. pointer to access the regular DiskObject structure.  If you have something 
  22. in ndo_NormalImage and ndo_SelectedImage, then call RemapChunkyImage() 
  23. on them to obtain Image structures remapped to the specified screen.
  24.  
  25. If you know you're dealing with a chunky display, you might wish to handle 
  26. the chunky data yourself, which would be more efficient than remapping to 
  27. an Intuition Image structure and blitting back on your chunky screen.
  28. In that case, don't use RemapChunkyImage(), and handle the 
  29. ndo_#?Image->ChunkyData yourself.
  30.  
  31. Once you're done with your newicon, call FreeRemappedImage() on the 
  32. remapped images to free them up (if you used RemapChunkyImage()).  After 
  33. that, call FreeNewDiskObject() on your NewDiskObject structure (even if 
  34. you only used the DiskObject pointer from it!) to free it.
  35.  
  36. newicon.library/FreeNewDiskObject           newicon.library/FreeNewDiskObject
  37.  
  38.  
  39.    NAME
  40.       FreeNewDiskObject() -- Free all memory allocated in a NewDiskObject.
  41.  
  42.    SYNOPSIS
  43.       FreeNewDiskObject(newdiskobj)
  44.                            A0
  45.  
  46.       VOID  FreeNewDiskObject(struct NewDiskObject *);
  47.  
  48.  
  49.    FUNCTION
  50.       Pretty much like the standard icon.library FreeDiskObject() call.
  51.       It will deallocate any memory allocated for a NewDiskObject, and
  52.       the object itself.  This is the ONLY way to deallocate a NewDiskObject
  53.       structure that has been allocated by GetNewDiskObject().
  54.  
  55.       
  56.    INPUTS
  57.       newdiskobj -- A pointer to a NewDiskObject structure.
  58.  
  59.  
  60.    RESULT
  61.       None.
  62.  
  63.  
  64.    SEE ALSO
  65.       newicon.library/GetNewDiskObject(), icon.library/FreeDiskObject()
  66.  
  67. newicon.library/FreeRemappedImage           newicon.library/FreeRemappedImage
  68.  
  69.  
  70.    NAME
  71.       FreeRemappedImage() -- Frees a remapped image and its pens.
  72.  
  73.  
  74.    SYNOPSIS
  75.       FreeRemappedImage(image, screen)
  76.                           A0     A1
  77.  
  78.       VOID  FreeRemappedImage(struct Image *, struct Screen *)
  79.  
  80.  
  81.    FUNCTION
  82.       This function frees a remapped image and also frees its pens. 
  83.       Therefore you must call it only after you are done with the image:
  84.       if you call it while it is still displayed on the screen, your image
  85.       could see its colors mangled since the pens would be freed.
  86.  
  87.       You must supply a screen argument.  It must either be the same
  88.       passed to RemapChunkyImage, or NULL if the screen has been closed
  89.       in the meantime, so the pens don't need to be released.
  90.  
  91.  
  92.    INPUTS
  93.       image  -- A pointer to a remapped Image structure.
  94.  
  95.       screen -- A pointer to the Screen for which your ChunkyData was
  96.                 remapped, or NULL if the screen has been closed since then.
  97.  
  98.  
  99.    RESULT
  100.       None.
  101.  
  102.  
  103.    SEE ALSO
  104.       newicon.library/RemapChunkyImage()
  105.  
  106. newicon.library/GetDefNewDiskObject      newicon.library/GetDefNewDiskObject
  107.  
  108.    NAME
  109.         GetDefNewDiskObject - read default disk object, with NewIcons
  110.                               support. (V40)
  111.  
  112.    SYNOPSIS
  113.         newdiskobj = GetDefNewDiskObject(def_type)
  114.           D0                               D0
  115.  
  116.         struct NewDiskObject *GetDefNewDiskObject(LONG);
  117.  
  118.    FUNCTION
  119.         Pretty much like the standard icon.library GetDiskObject() call.
  120.         In fact, it merely calls it, embedding the returned disk object
  121.         in a NewDiskObject structure, with the NewIcons imagery if the
  122.         default disk object had any.
  123.  
  124.         The valid def_types can be found in workbench/workbench.h and
  125.         currently include WBDISK thru WBGARBAGE.  If the call fails,
  126.         it will return zero.  The reason for the failure may be obtained
  127.         via IoErr().
  128.  
  129.  
  130.    INPUTS
  131.         def_type - default icon type (WBDISK thru WBKICK).  Note that the
  132.                    define 'WBDEVICE' is not currently supported.
  133.  
  134.  
  135.    RESULTS
  136.         newdiskobj -- the default Workbench disk object in question
  137.  
  138.    SEE ALSO
  139.         icon.library/GetDefDiskObject()
  140.  
  141. newicon.library/GetNewDiskObject             newicon.library/GetNewDiskObject
  142.  
  143.  
  144.    NAME
  145.       GetNewDiskObject() -- Read a disk object, with NewIcons support.
  146.  
  147.    SYNOPSIS
  148.       newdiskobj = GetNewDiskObject(name)
  149.         D0                           A0
  150.  
  151.       struct NewDiskObject *GetNewDiskObject(char *);
  152.  
  153.    FUNCTION
  154.       Pretty much like the standard icon.library GetDiskObject() call.
  155.       It will read the Workbench disk object specified in the name parameter,
  156.       adding the ".info" suffix itself, and return a filled NewDiskObject
  157.       structure.  If the call fails, it returns zero.  The reason for the
  158.       failure can be obtained by calling IoError().
  159.       
  160.       This routine can be used if you wish to obtain a standard diskobject,
  161.       with separate pointers to NewIcons chunky data if there's NewIcons
  162.       imageries present in the loaded disk object.  No further processing
  163.       is done (i.e. the chunky data aren't remapped, etc...)
  164.        
  165.       Once finished with it, you must use FreeNewDiskObject() to free the
  166.       memory that was allocated for it.
  167.  
  168.  
  169.    INPUTS
  170.       name -- The name (char *) of the object (without the ".info" suffix).
  171.  
  172.  
  173.    RESULT
  174.       newdiskobj -- a filled NewDiskObject structure.  You must call
  175.                     FreeNewDiskObject() once you're done with it.
  176.  
  177.  
  178.    SEE ALSO
  179.       newicon.library/FreeNewDiskObject(), newicon.library/RemapChunkyData(),
  180.       icon.library/GetDiskObject()
  181.  
  182. newicon.library/PutNewDiskObject             newicon.library/PutNewDiskObject
  183.  
  184.  
  185.    NAME
  186.       PutNewDiskObject() -- write a NewDiskObject to disk.
  187.  
  188.    SYNOPSIS
  189.       status = PutNewDiskObject(name, newdiskobj)
  190.         D0                       A0     A1
  191.  
  192.       BOOL  PutNewDiskObject(char *, struct NewDiskObject *);
  193.  
  194.  
  195.    FUNCTION
  196.       Pretty much like the standard icon.library PutDiskObject() call.
  197.       This routine will write a NewDiskObject structure and its related
  198.       information to disk as a standard icon, encoding the chunky data
  199.       (if present in the structure) as NewIcons tooltypes in the process.
  200.  
  201.       The filename of the info file is specified as the name parameter,
  202.       which will automaticaly get the ".info" suffix added.  If the call
  203.       fails, it returns zero.  The reason for the failure can be obtained
  204.       by calling IoError().
  205.       
  206.  
  207.    INPUTS
  208.       name -- The name (* char) of the object (without the ".info" suffix).
  209.       newdiskobj -- A pointer to a NewDiskObject structure.
  210.  
  211.  
  212.    RESULT
  213.       status -- TRUE if the call was successfull, else FALSE.
  214.  
  215.  
  216.    SEE ALSO
  217.       newicon.library/FreeNewDiskObject(), 
  218.       newicon.library/GetNewDiskObject(), icon.library/PutDiskObject()
  219.  
  220. newicon.library/RemapChunkyImage             newicon.library/RemapChunkyImage
  221.  
  222.  
  223.    NAME
  224.       RemapChunkyImage() -- Remaps a chunky image to be displayed on screen
  225.  
  226.    SYNOPSIS
  227.       image = RemapChunkyImage(chunkyimage, screen)
  228.         D0                       A0           A1
  229.  
  230.       struct Image *RemapChunkyImage(struct ChunkyImage *, struct Screen *);
  231.  
  232.    FUNCTION
  233.       Remaps a ChunkyImage to be displayed on a screen.  Caller must either
  234.       be the owner of the screen, or have locked it.  Under KS 3.0 (V39) and
  235.       up, it will use ObtainBestPen() if screen has shareable pens.
  236.       Otherwise will use the available colors.
  237.  
  238.       The image is returned as an Intuition Image structure, remapped so
  239.       chunky data palette match as closely as possible with the target
  240.       screen's palette, depending on the precision setting chosen by the
  241.       user in the NewIconsPrefs editor, and the available pens.
  242.  
  243.       Once done with your image, you should call FreeRemappedImage() to free
  244.       it and any allocated pens.
  245.  
  246.  
  247.    INPUTS
  248.       chunkydata -- A pointer to a ChunkyImage structure.
  249.       screen     -- A pointer to the destination Screen.
  250.  
  251.  
  252.    RESULT
  253.       Image -- An Intuition Image structure, or NULL if it fails.
  254.  
  255.  
  256.    NOTES
  257.       If the user has enabled the RTG Mode in the NewIconsPrefs, then the
  258.       remapped image will be in Fast RAM (if there's any, else it will
  259.       try to allocate Chip RAM instead).
  260.  
  261.  
  262.    SEE ALSO
  263.       newicon.library/FreeRemappedImage()
  264.  
  265.